Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.awt
Class EventQueue

    java.lang.Object
      |
      +--java.awt.EventQueue

public class EventQueue
extends Object

`EventQueue` is a platform-independent class that queues events, both from the underlying peer classes and from trusted application classes.

It encapsulates asynchronous event dispatch machinery which extracts events from the queue and dispatches them by calling `dispatchEvent(AWTEvent)` method on this `EventQueue` with the event to be dispatched as an argument. The particular behavior of this machinery is implementation-dependent. The only requirements are that events which were actually enqueued to this queue (note that events being posted to the `EventQueue` can be coalesced) are dispatched:

Sequentially.
  That is, it is not permitted that several events from this queue are dispatched simultaneously.
In the same order as they are enqueued.
  That is, if `AWTEvent` A is enqueued to the `EventQueue` before `AWTEvent` B then event B will not be dispatched before event A.

Some browsers partition applets in different code bases into separate contexts, and establish walls between these contexts. In such a scenario, there will be one `EventQueue` per context. Other browsers place all applets into the same context, implying that there will be only a single, global `EventQueue` for all applets. This behavior is implementation-dependent. Consult your browser's documentation for more information.

Since:
  1.1

Constructor Summary
`EventQueue()`

Method Summary
`protected void` | `dispatchEvent(AWTEvent event)` Dispatches an event.
`static AWTEvent` | `getCurrentEvent()` Returns the the event currently being dispatched by the `EventQueue` associated with the calling thread.
`static long` | `getMostRecentEventTime()` Returns the timestamp of the most recent event that had a timestamp, and that was dispatched from the `EventQueue` associated with the calling thread.
`AWTEvent` | `getNextEvent()` Removes an event from the `EventQueue` and returns it.
`static void` | `invokeAndWait(Runnable runnable)` Causes `runnable` to have its `run` method called in the dispatch thread of the `EventQueue`.
`static void` | `invokeLater(Runnable runnable)` Causes `runnable` to have its `run` method called in the dispatch thread of the `EventQueue`.
`static boolean` | `isDispatchThread()` Returns true if the calling thread is the current AWT `EventQueue`'s dispatch thread.
`AWTEvent` | `peekEvent()` Returns the first event on the `EventQueue` without removing it.
`AWTEvent` | `peekEvent(int id)` Returns the first event with the specified id, if any.
`protected void` | `pop()` Stops dispatching events using this `EventQueue`.
`void` | `postEvent(AWTEvent theEvent)` Posts a 1.1-style event to the `EventQueue`.
`void` | `push(EventQueue newEventQueue)` Replaces the existing `EventQueue` with the specified one.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### EventQueue

    public EventQueue()

Method Detail

### postEvent

    public void postEvent(AWTEvent theEvent)

  Posts a 1.1-style event to the `EventQueue`. If there is an existing event on the queue with the same ID and event source, the source `Component`'s `coalesceEvents` method will be called.

  Parameters:
    `theEvent` - an instance of `java.awt.AWTEvent`, or a subclass of it

### getNextEvent

    public AWTEvent getNextEvent()
                          throws InterruptedException

  Removes an event from the `EventQueue` and returns it. This method will block until an event has been posted by another thread.

  Returns:
    the next `AWTEvent`
  Throws:
    `InterruptedException` - if another thread has interrupted this thread

### peekEvent

    public AWTEvent peekEvent()

  Returns the first event on the `EventQueue` without removing it.

  Returns:
    the first event

### peekEvent

    public AWTEvent peekEvent(int id)

  Returns the first event with the specified id, if any.

  Parameters:
    `id` - the id of the type of event desired
  Returns:
    the first event of the specified id or `null` if there is no such event

### dispatchEvent

    protected void dispatchEvent(AWTEvent event)

  Dispatches an event. The manner in which the event is dispatched depends upon the type of the event and the type of the event's source object:

  Event Type | Source Type | Dispatched To
  --- | --- | ---
  ActiveEvent | Any | event.dispatch()
  Other | Component | source.dispatchEvent(AWTEvent)
  Other | MenuComponent | source.dispatchEvent(AWTEvent)
  Other | Other | No action (ignored)

### getMostRecentEventTime

    public static long getMostRecentEventTime()

  Returns the timestamp of the most recent event that had a timestamp, and that was dispatched from the `EventQueue` associated with the calling thread. If an event with a timestamp is currently being dispatched, its timestamp will be returned. If no events have yet been dispatched, the EventQueue's initialization time will be returned instead.In the current version of the Java platform SDK, only `InputEvent`s, `ActionEvent`s, and `InvocationEvent`s have timestamps; however, future versions of the SDK may add timestamps to additional event types. Note that this method should only be invoked from an application's event dispatching thread. If this method is invoked from another thread, the current system time (as reported by `System.currentTimeMillis()`) will be returned instead.

  Returns:
    the timestamp of the last `InputEvent`, `ActionEvent`, or `InvocationEvent` to be dispatched, or `System.currentTimeMillis()` if this method is invoked on a thread other than an event dispatching thread
  Since:
    1.4
See Also:
  `InputEvent.getWhen()`, `ActionEvent.getWhen()`, `InvocationEvent.getWhen()`

### getCurrentEvent

    public static AWTEvent getCurrentEvent()

  Returns the the event currently being dispatched by the `EventQueue` associated with the calling thread. This is useful if a method needs access to the event, but was not designed to receive a reference to it as an argument. Note that this method should only be invoked from an application's event dispatching thread. If this method is invoked from another thread, null will be returned.

  Returns:
    the event currently being dispatched, or null if this method is invoked on a thread other than an event dispatching thread
  Since:
    1.4

### push

    public void push(EventQueue newEventQueue)

  Replaces the existing `EventQueue` with the specified one. Any pending events are transferred to the new `EventQueue` for processing by it.

  Parameters:
    `newEventQueue` - an `EventQueue` (or subclass thereof) instance to be use
  See Also:
    `pop()`

### pop

    protected void pop()
                throws EmptyStackException

  Stops dispatching events using this `EventQueue`. Any pending events are transferred to the previous `EventQueue` for processing.

  Warning: To avoid deadlock, do not declare this method synchronized in a subclass.

  Throws:
    `EmptyStackException` - if no previous push was made on this `EventQueue`
  See Also:
    `push(java.awt.EventQueue)`

### isDispatchThread

    public static boolean isDispatchThread()

  Returns true if the calling thread is the current AWT `EventQueue`'s dispatch thread. Use this call the ensure that a given task is being executed (or not being) on the current AWT `EventDispatchThread`.

  Returns:
    true if running on the current AWT `EventQueue`'s dispatch thread

### invokeLater

    public static void invokeLater(Runnable runnable)

  Causes `runnable` to have its `run` method called in the dispatch thread of the `EventQueue`. This will happen after all pending events are processed.

  Parameters:
    `runnable` - the `Runnable` whose `run` method should be executed synchronously on the `EventQueue`
  Since:
    1.2
See Also:
  `invokeAndWait(java.lang.Runnable)`

### invokeAndWait

    public static void invokeAndWait(Runnable runnable)
                              throws InterruptedException,
                                     InvocationTargetException

  Causes `runnable` to have its `run` method called in the dispatch thread of the `EventQueue`. This will happen after all pending events are processed. The call blocks until this has happened. This method will throw an Error if called from the event dispatcher thread.

  Parameters:
    `runnable` - the `Runnable` whose `run` method should be executed synchronously on the `EventQueue`
  Throws:
    `InterruptedException` - if another thread has interrupted this thread
    `InvocationTargetException` - if an exception is thrown when running `runnable`
  Since:
    1.2
See Also:
  `invokeLater(java.lang.Runnable)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.